Agents & Models

Agentty delegates coding work to external AI agent CLIs. Each backend is a standalone CLI tool that Agentty launches in an isolated worktree. This page covers the supported backends, available models, and configuration options.

Supported Backends🔗

Agentty supports three agent backends. Each requires its respective CLI to be installed and available on your PATH.

File Path Output Format🔗

Agentty prompts all backends to reference files using repository-root-relative POSIX paths. This keeps file references consistent in session output and reviews.

• Allowed forms: path, path:line, path:line:column
• Example: crates/agentty/src/infra/agent/backend.rs:151
• Not allowed: absolute paths, file:// URIs, or ../-prefixed paths

Structured Response Protocol🔗

Agent responses should be a single JSON object with a messages array, where each entry has:

• type: answer or question
• text: markdown text payload

Example payload:

{
  "messages": [
    { "type": "answer", "text": "Implemented the change." },
    { "type": "question", "text": "Should I run the full test suite?" }
  ]
}

answer messages are appended to the normal session transcript. question messages are persisted separately and move the session to Question status so Agentty can collect clarifications in question input mode.

Protocol Validation and Repair🔗

Agentty validates final agent output against the structured response protocol.

• Claude and Gemini integrations use strict parsing and run one automatic repair retry loop (up to three repair turns) when output does not match the protocol schema.
• Claude turns use native schema validation via claude --json-schema and --output-format json (no Claude stream-json mode).
• Claude turns pass --strict-mcp-config, so only MCP servers explicitly provided by Agentty are allowed (none by default).
• Codex app-server turns enforce structured output through transport outputSchema; Codex prompts do not prepend schema text.
• Claude always uses structured protocol output (including utility/plain command paths) through native schema enforcement.
• Codex app-server turns include outputSchema at transport level and then use permissive final parsing fallback so non-schema text is still visible if needed.
• Partial protocol JSON fragments are suppressed during streaming so raw JSON wrappers do not leak into live transcript output.

Session Resume Behavior🔗

Agentty persists provider-native conversation identifiers for app-server backends and uses them to restore context after runtime restarts.

• Codex app-server: resumes by stored threadId via thread/resume.
• Gemini ACP: currently creates a fresh ACP session/new on runtime restart, so Agentty falls back to transcript replay when needed.

Codex Turn Timeout🔗

Codex app-server turns can run for a long time. Agentty waits up to 4 hours for Codex turn/completed by default.

Selecting a Backend🔗

Choose the backend from the /model picker:

# Open model selection (backend first, then model)
/model

For persistent defaults, choose a default model in the Settings tab (Tab to navigate, Enter to edit). The selected model determines which backend is used for new sessions.

For Codex sessions, the Settings tab also exposes Reasoning Level (low, medium, high, xhigh). The selected level is persisted and sent with Codex turns.

Available Models🔗

Each backend offers multiple models with different trade-offs between speed, quality, and cost.

Gemini Models🔗

Claude Models🔗

Codex Models🔗

Switching Models🔗

You can switch the model for the current session using the /model slash command in the prompt input. This opens a two-step picker: first choose the backend, then choose one of its models.

To change the default model persistently, use the Settings tab (Tab to navigate to it, Enter to edit).